// Copyright (c) 2012 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef CONTENT_PUBLIC_BROWSER_BROWSER_THREAD_H_
#define CONTENT_PUBLIC_BROWSER_BROWSER_THREAD_H_

#include <string>

#include "base/callback.h"
#include "base/location.h"
#include "base/logging.h"
#include "base/macros.h"
#include "base/memory/ref_counted.h"
#include "base/single_thread_task_runner.h"
#include "base/task_runner_util.h"
#include "base/time/time.h"
#include "content/common/content_export.h"

namespace base {
class MessageLoop;
class SequencedWorkerPool;
class Thread;
}

namespace content {

class BrowserThreadDelegate;
class BrowserThreadImpl;

// Use DCHECK_CURRENTLY_ON(BrowserThread::ID) to assert that a function can only
// be called on the named BrowserThread.
#define DCHECK_CURRENTLY_ON(thread_identifier)                         \
    (DCHECK(::content::BrowserThread::CurrentlyOn(thread_identifier))  \
        << ::content::BrowserThread::GetDCheckCurrentlyOnErrorMessage( \
               thread_identifier))

///////////////////////////////////////////////////////////////////////////////
// BrowserThread
//
// Utility functions for threads that are known by a browser-wide
// name.  For example, there is one IO thread for the entire browser
// process, and various pieces of code find it useful to retrieve a
// pointer to the IO thread's message loop.
//
// Invoke a task by thread ID:
//
//   BrowserThread::PostTask(BrowserThread::IO, FROM_HERE, task);
//
// The return value is false if the task couldn't be posted because the target
// thread doesn't exist.  If this could lead to data loss, you need to check the
// result and restructure the code to ensure it doesn't occur.
//
// This class automatically handles the lifetime of different threads.
// It's always safe to call PostTask on any thread.  If it's not yet created,
// the task is deleted.  There are no race conditions.  If the thread that the
// task is posted to is guaranteed to outlive the current thread, then no locks
// are used.  You should never need to cache pointers to MessageLoops, since
// they're not thread safe.
class CONTENT_EXPORT BrowserThread {
public:
    // An enumeration of the well-known threads.
    // NOTE: threads must be listed in the order of their life-time, with each
    // thread outliving every other thread below it.
    enum ID {
        // The main thread in the browser.
        UI,

        // This is the thread that interacts with the database.
        DB,

        // This is the thread that interacts with the file system.
        FILE,

        // Used for file system operations that block user interactions.
        // Responsiveness of this thread affect users.
        FILE_USER_BLOCKING,

        // Used to launch and terminate Chrome processes.
        PROCESS_LAUNCHER,

        // This is the thread to handle slow HTTP cache operations.
        CACHE,

        // This is the thread that processes non-blocking IO, i.e. IPC and network.
        // Blocking IO should happen on other threads like DB, FILE,
        // FILE_USER_BLOCKING and CACHE depending on the usage.
        IO,

        // NOTE: do not add new threads here that are only used by a small number of
        // files. Instead you should just use a Thread class and pass its
        // task runner around. Named threads there are only for threads that
        // are used in many places.

        // This identifier does not represent a thread.  Instead it counts the
        // number of well-known threads.  Insert new well-known threads before this
        // identifier.
        ID_COUNT
    };

    // These are the same methods in message_loop.h, but are guaranteed to either
    // get posted to the MessageLoop if it's still alive, or be deleted otherwise.
    // They return true iff the thread existed and the task was posted.  Note that
    // even if the task is posted, there's no guarantee that it will run, since
    // the target thread may already have a Quit message in its queue.
    static bool PostTask(ID identifier,
        const tracked_objects::Location& from_here,
        const base::Closure& task);
    static bool PostDelayedTask(ID identifier,
        const tracked_objects::Location& from_here,
        const base::Closure& task,
        base::TimeDelta delay);
    static bool PostNonNestableTask(ID identifier,
        const tracked_objects::Location& from_here,
        const base::Closure& task);
    static bool PostNonNestableDelayedTask(
        ID identifier,
        const tracked_objects::Location& from_here,
        const base::Closure& task,
        base::TimeDelta delay);

    static bool PostTaskAndReply(
        ID identifier,
        const tracked_objects::Location& from_here,
        const base::Closure& task,
        const base::Closure& reply);

    template <typename ReturnType, typename ReplyArgType>
    static bool PostTaskAndReplyWithResult(
        ID identifier,
        const tracked_objects::Location& from_here,
        const base::Callback<ReturnType(void)>& task,
        const base::Callback<void(ReplyArgType)>& reply)
    {
        scoped_refptr<base::SingleThreadTaskRunner> task_runner = GetTaskRunnerForThread(identifier);
        return base::PostTaskAndReplyWithResult(task_runner.get(), from_here, task,
            reply);
    }

    template <class T>
    static bool DeleteSoon(ID identifier,
        const tracked_objects::Location& from_here,
        const T* object)
    {
        return GetTaskRunnerForThread(identifier)->DeleteSoon(from_here, object);
    }

    template <class T>
    static bool ReleaseSoon(ID identifier,
        const tracked_objects::Location& from_here,
        const T* object)
    {
        return GetTaskRunnerForThread(identifier)->ReleaseSoon(from_here, object);
    }

    // Simplified wrappers for posting to the blocking thread pool. Use this
    // for doing things like blocking I/O.
    //
    // The first variant will run the task in the pool with no sequencing
    // semantics, so may get run in parallel with other posted tasks. The second
    // variant will all post a task with no sequencing semantics, and will post a
    // reply task to the origin TaskRunner upon completion.  The third variant
    // provides sequencing between tasks with the same sequence token name.
    //
    // These tasks are guaranteed to run before shutdown.
    //
    // If you need to provide different shutdown semantics (like you have
    // something slow and noncritical that doesn't need to block shutdown),
    // or you want to manually provide a sequence token (which saves a map
    // lookup and is guaranteed unique without you having to come up with a
    // unique string), you can access the sequenced worker pool directly via
    // GetBlockingPool().
    //
    // If you need to PostTaskAndReplyWithResult, use
    // base::PostTaskAndReplyWithResult() with GetBlockingPool() as the task
    // runner.
    static bool PostBlockingPoolTask(const tracked_objects::Location& from_here,
        const base::Closure& task);
    static bool PostBlockingPoolTaskAndReply(
        const tracked_objects::Location& from_here,
        const base::Closure& task,
        const base::Closure& reply);
    static bool PostBlockingPoolSequencedTask(
        const std::string& sequence_token_name,
        const tracked_objects::Location& from_here,
        const base::Closure& task);

    // For use with scheduling non-critical tasks for execution after startup.
    // The order or execution of tasks posted here is unspecified even when
    // posting to a SequencedTaskRunner and tasks are not guaranteed to be run
    // prior to browser shutdown.
    // When called after the browser startup is complete, will post |task|
    // to |task_runner| immediately.
    // Note: see related ContentBrowserClient::PostAfterStartupTask.
    static void PostAfterStartupTask(
        const tracked_objects::Location& from_here,
        const scoped_refptr<base::TaskRunner>& task_runner,
        const base::Closure& task);

    // Returns the thread pool used for blocking file I/O. Use this object to
    // perform random blocking operations such as file writes or querying the
    // Windows registry.
    static base::SequencedWorkerPool* GetBlockingPool() WARN_UNUSED_RESULT;

    // Callable on any thread.  Returns whether the given well-known thread is
    // initialized.
    static bool IsThreadInitialized(ID identifier) WARN_UNUSED_RESULT;

    // Callable on any thread.  Returns whether you're currently on a particular
    // thread.  To DCHECK this, use the DCHECK_CURRENTLY_ON() macro above.
    static bool CurrentlyOn(ID identifier) WARN_UNUSED_RESULT;

    // Callable on any thread.  Returns whether the threads message loop is valid.
    // If this returns false it means the thread is in the process of shutting
    // down.
    static bool IsMessageLoopValid(ID identifier) WARN_UNUSED_RESULT;

    // If the current message loop is one of the known threads, returns true and
    // sets identifier to its ID.  Otherwise returns false.
    static bool GetCurrentThreadIdentifier(ID* identifier) WARN_UNUSED_RESULT;

    // Callers can hold on to a refcounted task runner beyond the lifetime
    // of the thread.
    static scoped_refptr<base::SingleThreadTaskRunner> GetTaskRunnerForThread(
        ID identifier);

    // Sets the delegate for BrowserThread::IO.
    //
    // This only supports the IO thread as it doesn't work for potentially
    // redirected threads (ref. http://crbug.com/653916) and also doesn't make
    // sense for the UI thread.
    //
    // Only one delegate may be registered at a time. The delegate may be
    // unregistered by providing a nullptr pointer.
    //
    // If the caller unregisters the delegate before CleanUp has been called, it
    // must perform its own locking to ensure the delegate is not deleted while
    // unregistering.
    static void SetIOThreadDelegate(BrowserThreadDelegate* delegate);

    // Use these templates in conjunction with RefCountedThreadSafe or scoped_ptr
    // when you want to ensure that an object is deleted on a specific thread.
    // This is needed when an object can hop between threads
    // (i.e. IO -> FILE -> IO), and thread switching delays can mean that the
    // final IO tasks executes before the FILE task's stack unwinds.
    // This would lead to the object destructing on the FILE thread, which often
    // is not what you want (i.e. to unregister from NotificationService, to
    // notify other objects on the creating thread etc).
    template <ID thread>
    struct DeleteOnThread {
        template <typename T>
        static void Destruct(const T* x)
        {
            if (CurrentlyOn(thread)) {
                delete x;
            } else {
                if (!DeleteSoon(thread, FROM_HERE, x)) {
#if defined(UNIT_TEST)
                    // Only logged under unit testing because leaks at shutdown
                    // are acceptable under normal circumstances.
                    LOG(ERROR) << "DeleteSoon failed on thread " << thread;
#endif // UNIT_TEST
                }
            }
        }
        template <typename T>
        inline void operator()(T* ptr) const
        {
            enum { type_must_be_complete = sizeof(T) };
            Destruct(ptr);
        }
    };

    // Sample usage with RefCountedThreadSafe:
    // class Foo
    //     : public base::RefCountedThreadSafe<
    //           Foo, BrowserThread::DeleteOnIOThread> {
    //
    // ...
    //  private:
    //   friend struct BrowserThread::DeleteOnThread<BrowserThread::IO>;
    //   friend class base::DeleteHelper<Foo>;
    //
    //   ~Foo();
    //
    // Sample usage with scoped_ptr:
    // std::unique_ptr<Foo, BrowserThread::DeleteOnIOThread> ptr;
    struct DeleteOnUIThread : public DeleteOnThread<UI> {
    };
    struct DeleteOnIOThread : public DeleteOnThread<IO> {
    };
    struct DeleteOnFileThread : public DeleteOnThread<FILE> {
    };
    struct DeleteOnDBThread : public DeleteOnThread<DB> {
    };

    // Returns an appropriate error message for when DCHECK_CURRENTLY_ON() fails.
    static std::string GetDCheckCurrentlyOnErrorMessage(ID expected);

private:
    friend class BrowserThreadImpl;

    BrowserThread() { }
    DISALLOW_COPY_AND_ASSIGN(BrowserThread);
};

} // namespace content

#endif // CONTENT_PUBLIC_BROWSER_BROWSER_THREAD_H_
